home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / perl5 / AutoLoader.z / AutoLoader
Encoding:
Text File  |  1998-10-30  |  9.8 KB  |  199 lines
  1.  
  2.  
  3.  
  4. AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr((((3333))))                                                    AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      AutoLoader - load subroutines only on demand
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.          package Foo;
  13.          use AutoLoader 'AUTOLOAD';   # import the default AUTOLOAD subroutine
  14.  
  15.          package Bar;
  16.          use AutoLoader;              # don't import AUTOLOAD, define our own
  17.          sub AUTOLOAD {
  18.              ...
  19.              $AutoLoader::AUTOLOAD = "...";
  20.              goto &AutoLoader::AUTOLOAD;
  21.          }
  22.  
  23.  
  24. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  25.      The AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr module works with the AAAAuuuuttttooooSSSSpppplllliiiitttt module and the __END__
  26.      token to defer the loading of some subroutines until they are used rather
  27.      than loading them all at once.
  28.  
  29.      To use AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr, the author of a module has to place the definitions of
  30.      subroutines to be autoloaded after an __END__ token.  (See the _p_e_r_l_d_a_t_a
  31.      manpage.)  The AAAAuuuuttttooooSSSSpppplllliiiitttt module can then be run manually to extract the
  32.      definitions into individual files _a_u_t_o/_f_u_n_c_n_a_m_e._a_l.
  33.  
  34.      AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr implements an AUTOLOAD subroutine.  When an undefined
  35.      subroutine in is called in a client module of AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr, AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr's
  36.      AUTOLOAD subroutine attempts to locate the subroutine in a file with a
  37.      name related to the location of the file from which the client module was
  38.      read.  As an example, if _P_O_S_I_X._p_m is located in
  39.      /_u_s_r/_l_o_c_a_l/_l_i_b/_p_e_r_l_5/_P_O_S_I_X._p_m, AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr will look for perl subroutines
  40.      PPPPOOOOSSSSIIIIXXXX in /_u_s_r/_l_o_c_a_l/_l_i_b/_p_e_r_l_5/_a_u_t_o/_P_O_S_I_X/*._a_l, where the .al file has the
  41.      same name as the subroutine, sans package.  If such a file exists,
  42.      AUTOLOAD will read and evaluate it, thus (presumably) defining the needed
  43.      subroutine.  AUTOLOAD will then goto the newly defined subroutine.
  44.  
  45.      Once this process completes for a given funtion, it is defined, so future
  46.      calls to the subroutine will bypass the AUTOLOAD mechanism.
  47.  
  48.      SSSSuuuubbbbrrrroooouuuuttttiiiinnnneeee SSSSttttuuuubbbbssss
  49.  
  50.      In order for object method lookup and/or prototype checking to operate
  51.      correctly even when methods have not yet been defined it is necessary to
  52.      "forward declare" each subroutine (as in sub NAME;).  See the section on
  53.      _S_Y_N_O_P_S_I_S in the _p_e_r_l_s_u_b manpage.  Such forward declaration creates
  54.      "subroutine stubs", which are place holders with no code.
  55.  
  56.      The AutoSplit and AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr modules automate the creation of forward
  57.      declarations.  The AutoSplit module creates an 'index' file containing
  58.      forward declarations of all the AutoSplit subroutines.  When the
  59.      AutoLoader module is 'use'd it loads these declarations into its callers
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr((((3333))))                                                    AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr((((3333))))
  71.  
  72.  
  73.  
  74.      package.
  75.  
  76.      Because of this mechanism it is important that AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr is always used
  77.      and not required.
  78.  
  79.      UUUUssssiiiinnnngggg AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr's AUTOLOAD Subroutine
  80.  
  81.      In order to use AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr's AUTOLOAD subroutine you _m_u_s_t explicitly
  82.      import it:
  83.  
  84.          use AutoLoader 'AUTOLOAD';
  85.  
  86.  
  87.      OOOOvvvveeeerrrrrrrriiiiddddiiiinnnngggg AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr's AUTOLOAD Subroutine
  88.  
  89.      Some modules, mainly extensions, provide their own AUTOLOAD subroutines.
  90.      They typically need to check for some special cases (such as constants)
  91.      and then fallback to AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr's AUTOLOAD for the rest.
  92.  
  93.      Such modules should _n_o_t import AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr's AUTOLOAD subroutine.
  94.      Instead, they should define their own AUTOLOAD subroutines along these
  95.      lines:
  96.  
  97.          use AutoLoader;
  98.          use Carp;
  99.  
  100.          sub AUTOLOAD {
  101.              my $constname;
  102.              ($constname = $AUTOLOAD) =~ s/.*:://;
  103.              my $val = constant($constname, @_ ? $_[0] : 0);
  104.              if ($! != 0) {
  105.                  if ($! =~ /Invalid/) {
  106.                      $AutoLoader::AUTOLOAD = $AUTOLOAD;
  107.                      goto &AutoLoader::AUTOLOAD;
  108.                  }
  109.                  else {
  110.                      croak "Your vendor has not defined constant $constname";
  111.                  }
  112.              }
  113.              *$AUTOLOAD = sub { $val }; # same as: eval "sub $AUTOLOAD { $val }";
  114.              goto &$AUTOLOAD;
  115.          }
  116.  
  117.      If any module's own AUTOLOAD subroutine has no need to fallback to the
  118.      AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit
  119.      subroutines), then that module should not use AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr at all.
  120.  
  121.      PPPPaaaacccckkkkaaaaggggeeee LLLLeeeexxxxiiiiccccaaaallllssss
  122.  
  123.      Package lexicals declared with my in the main block of a package using
  124.      AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr will not be visible to auto-loaded subroutines, due to the
  125.      fact that the given scope ends at the __END__ marker.  A module using
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr((((3333))))                                                    AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr((((3333))))
  137.  
  138.  
  139.  
  140.      such variables as package globals will not work properly under the
  141.      AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr.
  142.  
  143.      The vars pragma (see the section on _v_a_r_s in the _p_e_r_l_m_o_d manpage) may be
  144.      used in such situations as an alternative to explicitly qualifying all
  145.      globals with the package namespace.  Variables pre-declared with this
  146.      pragma will be visible to any autoloaded routines (but will not be
  147.      invisible outside the package, unfortunately).
  148.  
  149.      AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr vs. SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr
  150.  
  151.      The AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr is similar in purpose to SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr: both delay the
  152.      loading of subroutines.
  153.  
  154.      SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr uses the __DATA__ marker rather than __END__.  While this
  155.      avoids the use of a hierarchy of disk files and the associated open/close
  156.      for each routine loaded, SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr suffers a startup speed disadvantage
  157.      in the one-time parsing of the lines after __DATA__, after which routines
  158.      are cached.  SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr can also handle multiple packages in a file.
  159.  
  160.      AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr only reads code as it is requested, and in many cases should
  161.      be faster, but requires a machanism like AAAAuuuuttttooooSSSSpppplllliiiitttt be used to create the
  162.      individual files.  the _E_x_t_U_t_i_l_s::_M_a_k_e_M_a_k_e_r manpage will invoke AAAAuuuuttttooooSSSSpppplllliiiitttt
  163.      automatically if AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr is used in a module source file.
  164.  
  165. CCCCAAAAVVVVEEEEAAAATTTTSSSS
  166.      AutoLoaders prior to Perl 5.002 had a slightly different interface.  Any
  167.      old modules which use AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr should be changed to the new calling
  168.      style.  Typically this just means changing a require to a use, adding the
  169.      explicit 'AUTOLOAD' import if needed, and removing AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr from @ISA.
  170.  
  171.      On systems with restrictions on file name length, the file corresponding
  172.      to a subroutine may have a shorter name that the routine itself.  This
  173.      can lead to conflicting file names.  The _A_u_t_o_S_p_l_i_t package warns of these
  174.      potential conflicts when used to split a module.
  175.  
  176. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  177.      the _S_e_l_f_L_o_a_d_e_r manpage - an autoloader that doesn't use external files.
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.